Getting and Setting Picture Geometries (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / Using Picture Shapes

Getting and Setting Picture Geometries
QuickDraw GX provides the GXGetPicture function and the GXSetPicture function to allow you to examine and replace the entire geometry of a picture shape.
The GXGetPicture function returns as its function result the number of items in the picture, and optionally returns an array of references to the shapes referenced by the picture's items, as well as arrays of references to the picture items' overriding styles, inks, and transforms. Typically, you call this function twice. The first time, you determine the number of items in the picture. Then you use that number to allocate enough memory to hold the arrays of references. Finally, you call the function a second time to copy references from the items of the picture into your arrays.
The GXSetPicture function allows you to replace the geometry of a picture with a new set of items. This function increments the owner counts of the new shapes, overriding styles, overriding inks, and overriding transforms and disposes of the original shapes, overriding styles, overriding inks, and overriding transforms.
Listing 6-3 gives an example of the GXGetPicture function. This example, which builds on the example from Listing 6-1 on page 6-28, edits the picture of the house by moving the location of the door.
Listing 6-3 Extracting and editing items from a picture
gxShape  *extractedShapes;

long     numberOfItems;
.
.
.
numberOfItems = GXGetPicture(housePicture, nil, nil, nil, nil);
extractedShapes = (gxShape *) 
                  NewPtr(numberOfItems * sizeof(gxShape));
GXGetPicture(housePicture, extractedShapes, nil, nil, nil);

GXMoveShape(extractedShapes[2], ff(-40), 0);

GXDrawShape(housePicture);
The code in Listing 6-3 includes two new variable declarations: a pointer to shape references and a long integer. The code in this listing calls the GXGetPicture function to determine the number of items in the house picture, uses that number to allocate enough memory to store the appropriate number of shape references, and then calls the GXGetPicture function a second time to copy the shape references from the items of the picture into the array of shape references. The sample code then uses the GXMoveShape function to move the third shape in the picture 40 grid points to the left. Notice that the extractedShapes array does not contain copies of the shapes in the picture; instead, it contains copies of references to the shapes in the picture. The references in the extractedShapes array reference the actual shapes in the picture. Therefore, moving the shape referenced by the third item in the extractedShapes array actually affects the house picture, as shown in Figure 6-20.
Figure 6-20 A picture of a house with a relocated door

For more information about the GXGetPicture and GXSetPicture functions, see page 6-59 through page 6-63.